feat: add Jarvis March (Gift Wrapping) convex hull algorithm #14225

AliAlimohammadi · 2026-01-30T00:55:26Z

Description

This PR adds an implementation of the Jarvis March algorithm (also known as the Gift Wrapping algorithm) for computing the convex hull of a set of 2D points.

The convex hull is the smallest convex polygon that contains all given points. The Jarvis March algorithm is an output-sensitive algorithm with time complexity $O(n·h)$, where $n$ is the number of input points and $h$ is the number of points on the convex hull.

What's Included

jarvis_march.py: Complete implementation in the geometry directory
Point class: Represents 2D coordinates
Helper functions: Cross product calculation and point-on-segment detection
Comprehensive doctests: 33 tests covering various scenarios including:
- Simple shapes (triangles, rectangles)
- Complex shapes (star patterns)
- Edge cases (collinear points, duplicate points, too few points)
- Interior points exclusion

Algorithm Details

Time Complexity: $O(n·h)$ where $n$ is the number of points and $h$ is the hull size
Space Complexity: $O(h)$ for storing hull points
Approach:
1. Find the leftmost point as the starting point
2. Iteratively select the most counter-clockwise point from the current point
3. Handle collinear points to avoid adding unnecessary vertices
4. Return empty list for degenerate cases (< 3 non-collinear points)

Testing

All doctests pass successfully:

$ python jarvis_march.py -v
33 tests in 9 items.
33 passed and 0 failed.
Test passed.

References

Checklist

Code follows the repository's style guidelines
Comprehensive docstrings with examples
All doctests pass
Type hints included
Algorithm has proper documentation with complexity analysis
No duplicate of existing algorithms in the repository

algorithms-keeper

Click here to look at the relevant links ⬇️

🔗 Relevant Links

Repository:

Contributing guidelines

Project Euler solution guidelines

Python:

Formatted string literals (f-strings)

Type hints

doctest

unittest

pytest

Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.

algorithms-keeper commands and options

algorithms-keeper actions can be triggered by commenting on this PR:

@algorithms-keeper review to trigger the checks for only added pull request files

@algorithms-keeper review-all to trigger the checks for all the pull request files, including the modified files. As we cannot post review comments on lines not part of the diff, this command will post all the messages in one comment.

NOTE: Commands are in beta and so this feature is restricted only to a member or owner of the organization.

geometry/jarvis_march.py

AliAlimohammadi · 2026-01-30T02:29:43Z

@poyea, this is ready to be merged.

geometry/jarvis_march.py

algorithms-keeper

Click here to look at the relevant links ⬇️

🔗 Relevant Links

Repository:

Contributing guidelines

Project Euler solution guidelines

Python:

Formatted string literals (f-strings)

Type hints

doctest

unittest

pytest

Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.

algorithms-keeper commands and options

algorithms-keeper actions can be triggered by commenting on this PR:

@algorithms-keeper review to trigger the checks for only added pull request files

@algorithms-keeper review-all to trigger the checks for all the pull request files, including the modified files. As we cannot post review comments on lines not part of the diff, this command will post all the messages in one comment.

NOTE: Commands are in beta and so this feature is restricted only to a member or owner of the organization.

algorithms-keeper · 2026-02-02T06:19:08Z

geometry/jarvis_march.py

+        self.x = x_coordinate
+        self.y = y_coordinate
+
+    def __eq__(self, other: object) -> bool:


As there is no test file in this pull request nor any test function or class in the file geometry/jarvis_march.py, please provide doctest for the function __eq__

algorithms-keeper · 2026-02-02T06:19:08Z

geometry/jarvis_march.py

+            return NotImplemented
+        return self.x == other.x and self.y == other.y
+
+    def __repr__(self) -> str:


As there is no test file in this pull request nor any test function or class in the file geometry/jarvis_march.py, please provide doctest for the function __repr__

algorithms-keeper · 2026-02-02T06:19:08Z

geometry/jarvis_march.py

+    def __repr__(self) -> str:
+        return f"Point({self.x}, {self.y})"
+
+    def __hash__(self) -> int:


As there is no test file in this pull request nor any test function or class in the file geometry/jarvis_march.py, please provide doctest for the function __hash__

algorithms-keeper · 2026-02-02T06:19:08Z

geometry/jarvis_march.py

+        return hash((self.x, self.y))
+
+
+def _cross_product(origin: Point, point_a: Point, point_b: Point) -> float:


As there is no test file in this pull request nor any test function or class in the file geometry/jarvis_march.py, please provide doctest for the function _cross_product

algorithms-keeper · 2026-02-02T06:19:08Z

geometry/jarvis_march.py

+    )
+
+
+def _is_point_on_segment(p1: Point, p2: Point, point: Point) -> bool:


As there is no test file in this pull request nor any test function or class in the file geometry/jarvis_march.py, please provide doctest for the function _is_point_on_segment

algorithms-keeper · 2026-02-02T06:19:08Z

geometry/jarvis_march.py

+    ) <= point.y <= max(p1.y, p2.y)
+
+
+def jarvis_march(points: list[Point]) -> list[Point]:


As there is no test file in this pull request nor any test function or class in the file geometry/jarvis_march.py, please provide doctest for the function jarvis_march

Add Jarvis March (Gift Wrapping) convex hull algorithm

f347c7f

algorithms-keeper bot added the require descriptive names This PR needs descriptive function and/or variable names label Jan 30, 2026

algorithms-keeper bot reviewed Jan 30, 2026

View reviewed changes

geometry/jarvis_march.py Outdated Show resolved Hide resolved

geometry/jarvis_march.py Outdated Show resolved Hide resolved

algorithms-keeper bot added the awaiting reviews This PR is ready to be reviewed label Jan 30, 2026

Use descriptive parameter names per algorithms-keeper review

7028fa7

algorithms-keeper bot removed the require descriptive names This PR needs descriptive function and/or variable names label Jan 30, 2026

poyea reviewed Jan 31, 2026

View reviewed changes

geometry/jarvis_march.py Show resolved Hide resolved

Update jarvis_march.py

5460dca

AliAlimohammadi requested a review from poyea February 2, 2026 05:54

algorithms-keeper bot added the tests are failing Do not merge until tests pass label Feb 2, 2026

AliAlimohammadi added 3 commits February 1, 2026 22:02

Update jarvis_march.py

938e20b

fix: add pytest marker

c2c2e75

Update jarvis_march.py

a376a44

algorithms-keeper bot added the require tests Tests [doctest/unittest/pytest] are required label Feb 2, 2026

algorithms-keeper bot reviewed Feb 2, 2026

View reviewed changes

algorithms-keeper bot removed the tests are failing Do not merge until tests pass label Feb 2, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add Jarvis March (Gift Wrapping) convex hull algorithm #14225

feat: add Jarvis March (Gift Wrapping) convex hull algorithm #14225

Uh oh!

AliAlimohammadi commented Jan 30, 2026 •

edited

Loading

Uh oh!

algorithms-keeper bot left a comment

Uh oh!

Uh oh!

Uh oh!

AliAlimohammadi commented Jan 30, 2026

Uh oh!

Uh oh!

algorithms-keeper bot left a comment

Uh oh!

algorithms-keeper bot Feb 2, 2026

Uh oh!

algorithms-keeper bot Feb 2, 2026

Uh oh!

algorithms-keeper bot Feb 2, 2026

Uh oh!

algorithms-keeper bot Feb 2, 2026

Uh oh!

algorithms-keeper bot Feb 2, 2026

Uh oh!

algorithms-keeper bot Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		return hash((self.x, self.y))


		def _cross_product(origin: Point, point_a: Point, point_b: Point) -> float:

		)


		def _is_point_on_segment(p1: Point, p2: Point, point: Point) -> bool:

		) <= point.y <= max(p1.y, p2.y)


		def jarvis_march(points: list[Point]) -> list[Point]:

Uh oh!

feat: add Jarvis March (Gift Wrapping) convex hull algorithm #14225

Are you sure you want to change the base?

feat: add Jarvis March (Gift Wrapping) convex hull algorithm #14225

Uh oh!

Conversation

AliAlimohammadi commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What's Included

Algorithm Details

Testing

References

Checklist

Uh oh!

algorithms-keeper bot left a comment

Choose a reason for hiding this comment

🔗 Relevant Links

Repository:

Python:

Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.

algorithms-keeper actions can be triggered by commenting on this PR:

Uh oh!

Uh oh!

Uh oh!

AliAlimohammadi commented Jan 30, 2026

Uh oh!

Uh oh!

algorithms-keeper bot left a comment

Choose a reason for hiding this comment

🔗 Relevant Links

Repository:

Python:

Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.

algorithms-keeper actions can be triggered by commenting on this PR:

Uh oh!

algorithms-keeper bot Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

algorithms-keeper bot Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

algorithms-keeper bot Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

algorithms-keeper bot Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

algorithms-keeper bot Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

algorithms-keeper bot Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AliAlimohammadi commented Jan 30, 2026 •

edited

Loading